<!-- Copyright 2014 The Chromium Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file. -->

<link rel="import" href="/static/html/app-page.html">
<link rel="import" href="api-link.html">

<template>
  <app-page pageTitle="Documentation">

    <h1>What is Build?</h1>
    <p>A build is the element in buildbucket.</p>

    <h2>Structure</h2>
    <p>A Build JSON object may have the following keys:
      <ul>
        <li><code>id</code>: a unique ID of build, generated by buildbucket.
          Ids are monotonically decreasing integers. Queries return builds
          sorted by id, thus new builds are first.
          </li>
        <li><code>created_ts</code>: timestamp when the build was created.</li>
        <li><code>created_by</code>: identity string (e.g. email) of who made a
          request to create a build.</li>
        <li><code>bucket</code>: a string that defines what project/subproject a
          build belongs to. Required.</li>
        <li><code>tags</code>: indexed key-value pairs, such as
          <code>["buildername:Release", "requester:cq"]</code>. Builds can be
          searched by tags. Also see tag
          <a href="#docs/conventions">conventions</a>.</li>
        <li><code>parameters_json</code>: an immutable JSON blob passed by a
          build requester, represents build parameters. The format is specific
          to a build-system. Not reqiured by buildbucket, but may be
          required by a particular build-system, such as
          <a href="#docs/buildbot">Buildbot</a>.</li>
        <li><code>url</code>: a URL to a build-system-specific human-viewable
          page that displays build status. Set by a build-system when the build
          is started.</li>
        <li><code>lease_expiration_ts</code>: when current lease will
          expire, if any.</li>
        <li><code>lease_key</code>: a key generated by buildbucket to a leasee.
          The leasee must pass it when it mutates the build.</li>
        <li><code>status</code>: current status of the build, can be one of:
          <ul>
            <li><code>"SCHEDULED"</code>: available for processing.</li>
            <li><code>"STARTED"</code>: leased and is being processed.</li>
            <li><code>"COMPLETED"</code>: completed and cannot be changed.
              See <code>result</code> field for more info.</li>
          </ul></li>
        <li><code>status_changed_ts</code>: timestamp when last time build
          status has changed.</li>
        <li><code>completed_ts</code>: timestamp when the build was completed.
          </li>
        <li><code>result</code>: final result of the build. Can be set only in
          <code>COMPLETED</code> state. Can be one of:
          <ul>
            <li><code>"SUCCESS"</code>: the build has succeeded.</li>
            <li><code>"FAILURE"</code>: the build has failed. See
              <code>failure_reason</code> field for more info.</li>
            <li><code>"CANCELED"</code>: the build has been canceled. See
              <code>CancelationReason</code> for more info.</li>
          </ul></li>
        <li><code>result_details_json</code>: an immutable JSON blob passed by a
          build-system on build completion. Represents the result of the build.
          </li>
        <li><code>failure_reason</code>: why the build failed. Can be one of:
          <ul>
            <li><code>"BUILD_FAILURE"</code>: the build has failed normally, not
              due to an infrastructure failure.</li>
            <li><code>"INFRA_FAILURE"</code>: infrastructure failure happened.
              </li>
            <li><code>"BUILDBUCKET_FAILURE"</code>: buildbucket failure
              happened. </li>
            <li><code>"INVALID_BUILD_DEFINITION"</code>: a build system could
              not understand the definition of the build. See
              <code>result_details_json</code> for more info.</li>
          </ul></li>
        <li><code>cancelation_reason</code>: why the build was canceled. Can be
          one of:
          <ul>
            <li><code>"CANCELED_EXPLICITLY"</code>: the build canceled was
              requested externally.</li>
            <li><code>"TIMEOUT"</code>: the build was canceled on timeout.
              Not supported yet.</li>
          </ul></li>
        <li><code>updated_ts</code>: timestamp when the build was modified
          last time. A modification includes leasing.</li>
        <li><code>utcnow_ts</code>: current UTC time on the server.</li>
      </ul></p>

    <p>All timestamps are in microseconds since Unix Epoch.</p>

    <h2>Leasing a build</h2>
    <p>A build-system is supposed to <bb-api-link name="lease"></bb-api-link> a
      build before processing it. A build lease is exclusive and a build cannot
      be mutated without a lease. A leasee receives a <code>lease_key</code>
      that it uses for mutation. When a build is leased, it is not returned in
      <api-link name="peek"></api-link> API call.
      When build lease expires, buildbucket makes the build available again.</p>

  </app-page>
</template>
